The Dice Roll Controller (attached to the Gameboard node) exposes all the dice features available to creators.
The Gameboard node is always available in your game as long as the SDK has been integrated. In order to access it we just need to find it.
var gameboard = GetNode("/root/GameboardSDK") as GameboardPlugin;
With access to our Gameboard node we can then move on to obtain a reference to the Dice controller. This is the controller that handles all the functions related to dice.
We will first need to define a reference to the controller to make it available throughout our script:
DiceRollController diceController;
With our listener defined, we can now proceed to listen for dice events. In our case we'll have a function called OnDiceRolled handle this events.
diceController = gameboard.GetNode("DiceRollController") as DiceRollController;
diceController.OnDiceRolled += OnDiceRolled;
Now that we are able to receive the dice roll events all that remains is to handle them in the game.
void OnDiceRolled(CompanionDiceRollEventArgs diceRolledEvent)
{
// Handle Dice Rolls
}
With the controller at hand we can also send requests to Companion to prompt players to roll one or more dice. In this example we'll request a user whose ID user ID is "userABC" to roll a red d20 for us. The last two parameters are the addedModifier, and the dice notation. The dice notation is an optional parameter.
// Ask user with ID userABC to roll a d20
diceController.RollDice("userABC", new DieGroup[]
{
new DieGroup
{
sides = 20,
diceTintHexColor = Color.red
}
}, 0, "1d20")
// If not planning to do customizations for the rolls (different colors per dice, textures, ids), you can use this alternative method
diceController.RollDice("userABC", new int[] { 20 }, 0, Color.red, "RPG");
You can also request to roll different dice with varied colors/amounts. This will roll two 6 sided blue die, one 6 sided red die, and a d20 with a custom texture. Assume the assetId for the d20 texture is d20TextureId.
// Ask user with ID userABC to roll a d20
diceController.RollDice("userABC", new DieGroup[]
{
new DieGroup
{
id = "mana",
sides = 6,
count = 2,
diceTintHexColor = $"#{UnityEngine.ColorUtility.ToHtmlStringRGB(UnityEngine.Color.blue)}"
},
new DieGroup
{
id = "health",
sides = 6,
count = 1,
diceTintHexColor = $"#{UnityEngine.ColorUtility.ToHtmlStringRGB(UnityEngine.Color.red)}"
},
new DieGroup
{
sides = 20,
count = 1,
textureId = "d20TextureId"
},
}, 0, "2d6+1d6+1d20")
By default, the dice selector is available in the dice vie and allows the user to select the following default dice to roll.
If you do not want the user to be able to select dice to roll at will, you can hide the selector with the following:
diceController.SetDiceSelectorVisibility(userId, false);
You can also set what dice you want to be selectable within the selector. This example will make the selector show 3 dice options to roll. They will have the label specified, and if omitted the label will default to D{sides}. Assume the assetId for the d6 texture is d6TextureId. The provided ids will be sent back with the OnDiceRolled event, so you know which type of die was rolled.
diceController.SetSelectableDice("userABC", new DieGroup[]
{
new DieGroup
{
id = "textured-d6",
sides = 6,
label = "Modified d6"
textureId = "d6TextureId"
},
new DieGroup
{
id = "20-sided-die",
sides = 20,
},
new DieGroup
{
id = "m-d20",
sides = 20,
label = "Magenta d20",
diceTintHexColor = $"#{UnityEngine.ColorUtility.ToHtmlStringRGB(UnityEngine.Color.magenta)}",
},
})
This will display the following, where selecting the options will display dice with the properties specified.
You have the ability to send the results back to compaion to display.
If you are only looking to send back to overall results (which dice were rolled and their total), you just need to send the list of dice rolled (as DiceGroup objects), the modifier to add to the result, and the result. You would send false for the last property, which is a flag to show results full breakdown.
// Show the result of roll one d4, two d6s, and one d20 with a +1 modifier
var gameCalculatedResultTotal = 22;
diceController.SendRollResults("userABC", new DieGroup[]
{
new DieGroup
{
sides = 4,
count = 1
},
new DieGroup
{
sides = 6,
count = 2
},
new DieGroup
{
sides = 20,
count = 1
},
}, 1, gameCalculatedResultTotal, false)
If you want to display the full breakdown of the results, you can populate the results array within each DieGroup, with each value corresponding to a roll results.
// Show the result of roll one d4, two d6s, and one d20 with a +1 modifier
var gameCalculatedResultTotal = 22;
diceController.SendRollResults("userABC", new DieGroup[]
{
new DieGroup
{
sides = 4,
count = 1,
result = [2]
},
new DieGroup
{
sides = 6,
count = 2,
result = [3, 3]
},
new DieGroup
{
sides = 20,
count = 1,
result = [14]
},
}, 1, gameCalculatedResultTotal, true)
You can see the results on the left, and the optional full breakdown on the right side.
Although we are working in a managed environment it is always a good idea to clean the listeners when no longer needed.
public override void _ExitTree()
{
diceController.OnDiceRolled -= OnDiceRolled;
}
This section include the entire code in one single, easy to copy section.
DiceRollController diceController;
// Called when the node enters the scene tree for the first time.
public override void _Ready()
{
var gameboard = GetNode("/root/GameboardSDK") as GameboardPlugin;
diceController = gameboard.GetNode("DiceRollController") as DiceRollController;
diceController.OnDiceRolled += OnDiceRolled;
}
void OnDiceRolled(CompanionDiceRollEventArgs diceRolledEvent)
{
// Handle Dice Rolls
}
public override void _ExitTree()
{
diceController.OnDiceRolled -= OnDiceRolled;
}